packages/app/src/docker-git/main.ts (1)

9-17: 💤 Low value

Correct the EFFECT comment type signature for precision.

Line 13 shows Effect<void, unknown, NodeContext | HttpClient>, but Effect-TS conventions use the full service tag name HttpClient.HttpClient from @effect/platform/HttpClient. While this doesn't affect runtime behavior (the Layer.merge correctly provides both services), the comment should match the actual Effect type signature for documentation accuracy.

📝 Proposed fix

-// EFFECT: Effect<void, unknown, NodeContext | HttpClient>
+// EFFECT: Effect<void, unknown, NodeContext.NodeContext | HttpClient.HttpClient>

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/app/src/docker-git/main.ts` around lines 9 - 17, The EFFECT
comment's type signature is imprecise: replace `Effect<void, unknown,
NodeContext | HttpClient>` with the precise service tag name
`Effect.Effect<void, unknown, NodeContext | HttpClient.HttpClient>` (or the
project’s Effect alias) so it matches the actual provided service from
NodeContext.layer and FetchHttpClient.layer; update the comment near
mainLayer/main to reference `HttpClient.HttpClient` (the symbol exported by
`@effect/platform/HttpClient`) instead of `HttpClient` for accurate documentation.

packages/app/src/docker-git/tmux.ts (1)

294-339: ⚡ Quick win

Add TSDoc annotations for API documentation and guideline compliance.

The function has comprehensive functional comments (CHANGE, WHY, QUOTE, PURITY, EFFECT, INVARIANT, COMPLEXITY) but is missing TSDoc annotations required by coding guidelines. While the existing attachTmux function (lines 253-292) also lacks TSDoc, new code should follow the guidelines.

Add @pure false, @effect, @precondition, @postcondition, and @complexity annotations to both the ProjectInfo type and the attachTmuxFromProject function.

📋 Proposed TSDoc additions

+/**
+ * Project metadata provided by API for tmux session attachment.
+ * Used when CLI runs inside Docker and cannot access local filesystem.
+ */
 export type ProjectInfo = {
   readonly containerName: string
   readonly sshUser: string
   readonly sshPort: number
   readonly repoUrl: string
   readonly repoRef: string
   readonly sshCommand: string
 }

+/**
+ * Attach to a tmux workspace using API-provided project details.
+ * Checks for existing session and recreates if layout is outdated.
+ *
+ * `@param` project - Project metadata from API
+ * `@returns` Effect that attaches to tmux session
+ * `@pure` false
+ * `@effect` CommandExecutor.CommandExecutor
+ * `@invariant` tmux session name is deterministic from repoUrl
+ * `@precondition` tmux is installed and project.sshCommand is valid
+ * `@postcondition` user is attached to tmux session or error is raised
+ * `@complexity` O(1) - constant number of tmux commands
+ */
 // CHANGE: attach tmux from API project details without local filesystem access
 // WHY: in DinD, project files live on the API host; CLI cannot read them locally
 // QUOTE(ТЗ): "он сам бы подключался к API и всё делал бы сам"
 // PURITY: SHELL
 // EFFECT: Effect<void, CommandFailedError | PlatformError, CommandExecutor>
 // INVARIANT: tmux session name is deterministic from repoUrl; no local file reads
 // COMPLEXITY: O(1)
 export const attachTmuxFromProject = (

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/app/src/docker-git/tmux.ts` around lines 294 - 339, Add TSDoc
comments to the ProjectInfo type and the attachTmuxFromProject function: for
ProjectInfo document its fields and include `@precondition` describing required
non-empty containerName/sshUser/repoUrl and valid sshPort, and `@complexity` O(1);
for attachTmuxFromProject add a TSDoc block with `@pure` false, an `@effect`
describing it returns Effect<void, CommandFailedError | PlatformError,
CommandExecutor.CommandExecutor>, `@precondition` noting it requires reachable
API/host info in ProjectInfo, `@postcondition` explaining it will attach or
recreate a tmux session named dg-<repo-slug>, and `@complexity` O(1); place the
docs immediately above the ProjectInfo declaration and the attachTmuxFromProject
export to satisfy guideline parity with attachTmux.

packages/api/src/services/capture-output.ts (1)

10-32: ⚡ Quick win

Add TSDoc annotations for API documentation and guideline compliance.

The function has good functional comments (CHANGE, WHY, PURITY, EFFECT, INVARIANT, COMPLEXITY) but is missing TSDoc annotations required by coding guidelines. Add @pure false, @effect (Logger service), @precondition, @postcondition, and @complexity annotations.

Note on mutation (line 13): The mutable lines array is acceptable in SHELL-layer code as documented by PURITY: SHELL. The closure captures log output imperatively before returning immutable result. This is a standard pattern for bridging Effect's functional core with imperative logging.

📋 Proposed TSDoc addition

+/**
+ * Capture Effect.log output and return it as a string alongside the effect result.
+ *
+ * `@template` A - Success type of the input effect
+ * `@template` E - Error type of the input effect
+ * `@template` R - Requirements of the input effect
+ * `@param` effect - The Effect to capture log output from
+ * `@returns` Effect producing { result, output } with captured log lines
+ * `@pure` false
+ * `@effect` Logger (via Logger.replace), plus requirements R from input effect
+ * `@invariant` captured log lines are joined with newline separator
+ * `@precondition` effect must be a valid Effect
+ * `@postcondition` output contains all non-blank log messages as newline-joined string
+ * `@complexity` O(n) where n = number of log lines
+ */
 // CHANGE: capture Effect.log output so API can return it as JSON response
 // WHY: lib functions communicate results via Effect.log; REST API needs string output
 // PURITY: SHELL
 // EFFECT: Effect<{ result: A; output: string }, E, R>
 // INVARIANT: captured lines are joined with newline
 // COMPLEXITY: O(n) where n = log lines
 export const captureLogOutput = <A, E, R>(

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/capture-output.ts` around lines 10 - 32, Add TSDoc
to the captureLogOutput function: add a short description, mark it as `@pure
false`, add `@effect` noting it requires the Logger service, include
`@precondition` stating an Effect<A, E, R> is supplied, `@postcondition`
describing the returned Effect will produce an object `{ result: A; output:
string }` where output is the joined captured log lines, and `@complexity` (e.g.
O(n) in number of captured log entries). Reference the function name
`captureLogOutput` and note that the `lines` mutable array is confined to this
SHELL-layer implementation (closure over `lines`, created for
`Logger.make`/`captureLayer`) so mutation is acceptable. Ensure tags are placed
immediately above the `export const captureLogOutput` declaration.

packages/api/src/services/scrap.ts (3)

10-14: ⚡ Quick win

Add comprehensive TSDoc for the error conversion helper.

The toApiError helper lacks TSDoc documentation. Per coding guidelines, all functions must include comprehensive TSDoc with @pure, @effect, @invariant, @precondition, @postcondition, and @complexity.

📝 Suggested TSDoc

+/**
+ * Convert unknown error cause into typed ApiInternalError.
+ * `@pure` false
+ * `@effect` Effect<ApiInternalError, never, never>
+ * `@invariant` ∀ cause: toApiError(cause) instanceof ApiInternalError
+ * `@precondition` none
+ * `@postcondition` returned error wraps original cause as Error
+ * `@complexity` O(1) time, O(1) space
+ */
 const toApiError = (cause: unknown): ApiInternalError =>

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space), @throws Never (errors must be typed in Effect)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/scrap.ts` around lines 10 - 14, Add a comprehensive
TSDoc block above the toApiError function: document purpose, mark `@pure` true,
list `@effect` as none (or required services if any), state `@invariant` that output
is an ApiInternalError wrapping the provided cause, declare `@precondition` that
cause is non-nullable (or allow unknown) and `@postcondition` that returned object
is an ApiInternalError with message and cause properties set, include
`@complexity` O(1) time and O(1) space, and add `@throws` Never; ensure tags exactly
include `@pure`, `@effect`, `@invariant`, `@precondition`, `@postcondition`, and
`@complexity` per guidelines and reference the toApiError symbol in the comment.

---

35-47: ⚡ Quick win

Add comprehensive TSDoc for runScrapImport.

This exported function lacks any TSDoc. Per coding guidelines, all functions must document @pure, @effect, @invariant, @precondition, @postcondition, and @complexity.

📝 Suggested documentation

+// CHANGE: expose lib scrap import through REST API
+// WHY: CLI becomes HTTP client; scrap import runs on API server
+// PRECONDITION: req.archivePath exists and is readable
+// POSTCONDITION: scrap data imported into req.projectDir
+// COMPLEXITY: O(n) time where n = size of archive, O(n) space during extraction
+// PURITY: SHELL
+// EFFECT: Effect<{ output: string }, ApiInternalError, FileSystem | Path | CommandExecutor>
+// INVARIANT: captured log output forms the response body
 export const runScrapImport = (req: ScrapImportRequest) =>

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/scrap.ts` around lines 35 - 47, Add comprehensive
TSDoc to the exported function runScrapImport: include `@pure` (set to false
because it performs IO/effects), `@effect` (list required services like
captureLogOutput and importScrap side-effects), `@invariant` (e.g., output
returned is non-empty string or "Import complete."), `@precondition`
(req.projectDir and req.archivePath must be valid non-empty strings),
`@postcondition` (returns an Effect that resolves to { output: string } or a
mapped ApiError via toApiError), and `@complexity` (state expected time/space
complexity, e.g., O(n) time relative to archive size and O(1) additional
memory). Mention relevant symbols runScrapImport, importScrap, captureLogOutput,
and toApiError in the docblock for context.

---

16-33: ⚡ Quick win

Complete TSDoc documentation with missing mandatory fields.

The functional comments provide helpful context, but comprehensive TSDoc is incomplete. Missing @precondition, @postcondition, and @complexity markers required by coding guidelines.

📝 Add missing TSDoc fields

 // CHANGE: expose lib scrap functions through REST API
 // WHY: CLI becomes HTTP client; scrap export/import runs on API server
+// PRECONDITION: req.projectDir exists and is readable
+// POSTCONDITION: archive created at archivePath or default location
+// COMPLEXITY: O(n) time where n = size of scrap data, O(n) space for archive
 // PURITY: SHELL
 // EFFECT: Effect<SessionsOutput, ApiInternalError, FileSystem | Path | CommandExecutor>
 // INVARIANT: captured log output forms the response body

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/scrap.ts` around lines 16 - 33, Add complete TSDoc
above runScrapExport: keep the existing contextual lines
(PURITY/EFFECT/INVARIANT) and add mandatory tags `@precondition` (e.g.,
req.projectDir is non-empty and readable, archivePath writable when provided),
`@postcondition` (returns an Effect that resolves to an object with an "output"
string and maps internal errors via toApiError), and `@complexity` (state
time/space complexity of the operation, e.g., O(n) time / O(1) additional space
or justify otherwise). Include `@pure` (false) and list the required
services/effects under `@effect` mentioning captureLogOutput and exportScrap to
match the function behavior.

packages/api/src/services/state.ts (3)

26-36: ⚡ Quick win

Complete TSDoc documentation with missing mandatory fields.

The functional comments provide useful context, but several required TSDoc markers are missing.

📝 Add missing TSDoc fields

 // CHANGE: expose lib state-repo functions through REST API
 // WHY: CLI becomes HTTP client; all state operations run on API server
+// PRECONDITION: state repository initialized
+// POSTCONDITION: state path returned as trimmed string
+// COMPLEXITY: O(1) time, O(1) space
 // PURITY: SHELL
 // EFFECT: Effect<StatePathResponse | StateOutputResponse, ApiInternalError, Path>
 // INVARIANT: captured log messages form the response body

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/state.ts` around lines 26 - 36, Add full TSDoc for
the exported runStatePath function: above the runStatePath declaration document
the purpose, parameters/returns and include the required tags `@pure`
(true/false), `@effect` (list required services), `@invariant` (behavioral
invariants), `@precondition`, `@postcondition`, and `@complexity` (time and space).
Reference the implementation details (it calls captureLogOutput(statePath), maps
output to { path }, and maps errors with toApiError) in the description so
readers know the observable effects and error translation behavior; ensure the
`@effect` entry mentions captureLogOutput/statePath/toApiError as required
services or effects and set `@pure` appropriately.

---

38-47: ⚡ Quick win

Add comprehensive TSDoc for runStateInit.

This exported function lacks all required documentation markers.

📝 Suggested documentation

+// CHANGE: initialize state repository via REST API
+// WHY: enable state-repo setup through HTTP
+// PRECONDITION: req.repoUrl is valid git URL
+// POSTCONDITION: state repository cloned and initialized
+// COMPLEXITY: O(m) time where m = repository size, O(m) space
+// PURITY: SHELL
+// EFFECT: Effect<{ output: string }, ApiInternalError, FileSystem | Path | CommandExecutor>
+// INVARIANT: captured log output forms the response body
 export const runStateInit = (req: StateInitRequest) =>

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/state.ts` around lines 38 - 47, The exported
function runStateInit is missing the required comprehensive TSDoc; add a full
TSDoc block above its declaration that documents purpose and parameters, marks
purity with `@pure`, lists required services/effects (e.g., captureLogOutput and
stateInit usage) with `@effect`, states any invariants (e.g., output
normalization: returns "Done." when output is empty) with `@invariant`, specifies
preconditions (valid repoUrl/repoRef) and postconditions (returns an object with
output string, and maps errors via toApiError), and documents complexity
(time/space) and side-effects; reference the function name runStateInit and
mention related symbols stateInit, captureLogOutput, Effect.map, and toApiError
in the comments to make locating context explicit.

---

49-77: ⚡ Quick win

Add comprehensive TSDoc for remaining state functions.

The functions runStateStatus, runStatePull, runStatePush, runStateCommit, and runStateSync all lack required documentation.

📝 Suggested documentation pattern (apply to each)

For runStateStatus:

// CHANGE: get state repository status via REST API
// WHY: expose git status through HTTP
// PRECONDITION: state repository initialized
// POSTCONDITION: working tree status returned
// COMPLEXITY: O(n) time where n = number of files, O(n) space
// PURITY: SHELL
// EFFECT: Effect<{ output: string }, ApiInternalError, CommandExecutor | Path>
// INVARIANT: captured log output forms the response body

Apply similar patterns to runStatePull, runStatePush, runStateCommit, and runStateSync with appropriate preconditions/postconditions for their git operations.

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/state.ts` around lines 49 - 77, Add comprehensive
TSDoc to each exported function runStateStatus, runStatePull, runStatePush,
runStateCommit, and runStateSync following the project's pattern: include a
one-line description, CHANGE, WHY, and then `@precondition` and `@postcondition`
describing the git state (e.g., repo initialized, commit message provided for
runStateCommit, pull/push network available for runStatePull/runStatePush),
`@complexity` with time/space, `@pure` (true/false, mark SHELL as non-pure), `@effect`
listing required services (e.g., CommandExecutor | Path), and `@invariant`
describing the output (e.g., captured log output forms the response body);
mirror the suggested template in the review comment but adapt pre/postconditions
for each function (status = working tree status returned, pull/push = remote
sync completed, commit = commit created with message, sync = bidirectional sync
with message handling).

packages/api/src/services/sessions.ts (3)

18-34: ⚡ Quick win

Complete TSDoc documentation with missing mandatory fields.

The functional comments provide context, but comprehensive TSDoc is incomplete. Missing @precondition, @postcondition, and @complexity markers.

📝 Add missing TSDoc fields

 // CHANGE: expose lib terminal-sessions functions through REST API
 // WHY: CLI becomes HTTP client; session management runs on API server
+// PRECONDITION: req.projectDir exists
+// POSTCONDITION: list of terminal sessions returned
+// COMPLEXITY: O(n) time where n = number of sessions, O(n) space for output
 // PURITY: SHELL
 // EFFECT: Effect<SessionsOutput, ApiInternalError, FileSystem | Path | CommandExecutor>
 // INVARIANT: captured log output forms the response body

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/sessions.ts` around lines 18 - 34, Add full TSDoc
for the exported runSessionsList function (and update related helper
declarations if present) including the mandatory tags: `@pure` (true/false),
`@effect` (services required, e.g., FileSystem | Path | CommandExecutor),
`@invariant` (the captured log output forms the response body), `@precondition`
(expected shape/validity of SessionsListRequest, e.g., projectDir present),
`@postcondition` (response contains output string or "(no sessions)"), and
`@complexity` (time and space complexity); reference the function name
runSessionsList and the used helpers captureLogOutput, listTerminalSessions and
toApiError so the comments clearly describe inputs, side-effects and return
contract.

---

48-59: ⚡ Quick win

Add comprehensive TSDoc for runSessionsLogs.

This exported function lacks all required documentation markers.

📝 Suggested documentation

+// CHANGE: tail terminal session logs via REST API
+// WHY: provide log access through HTTP for debugging
+// PRECONDITION: req.pid exists with associated log file
+// POSTCONDITION: last n lines of session log returned
+// COMPLEXITY: O(k) time where k = req.lines, O(k) space for output
+// PURITY: SHELL
+// EFFECT: Effect<{ output: string }, ApiInternalError, FileSystem | Path | CommandExecutor>
+// INVARIANT: captured log output forms the response body
 export const runSessionsLogs = (req: SessionsLogsRequest) =>

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/sessions.ts` around lines 48 - 59, Add
comprehensive TSDoc to the exported function runSessionsLogs: document its
purity with `@pure` (true/false), list required services under `@effect`, state any
invariants under `@invariant`, list `@precondition` and `@postcondition` (e.g., input
shapes and that output string is non-empty or "(no output)"), and give
`@complexity` for time/space. Place the comment immediately above the
runSessionsLogs declaration and mention the main operations it composes
(captureLogOutput and tailTerminalLogs) so reviewers can see side effects and
required inputs; ensure `@param` and `@returns` are filled and include error
behavior (mapError toApiError) in the postcondition/effect.

---

36-46: ⚡ Quick win

Add comprehensive TSDoc for runSessionsKill.

This exported function lacks TSDoc documentation. All required markers (@pure, @effect, @invariant, @precondition, @postcondition, @complexity) are missing.

📝 Suggested documentation

+// CHANGE: kill terminal session process via REST API
+// WHY: provide session lifecycle management through HTTP
+// PRECONDITION: req.pid exists in req.projectDir terminal sessions
+// POSTCONDITION: process with req.pid terminated
+// COMPLEXITY: O(1) time, O(1) space
+// PURITY: SHELL
+// EFFECT: Effect<{ output: string }, ApiInternalError, FileSystem | Path | CommandExecutor>
+// INVARIANT: captured log output forms the response body
 export const runSessionsKill = (req: SessionsKillRequest) =>

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/sessions.ts` around lines 36 - 46, Add a TSDoc
block above the exported runSessionsKill function that documents its behavior
and required markers: state `@pure` (false), `@effect` (services used, e.g.,
captures logs and calls killTerminalProcess), `@invariant` (e.g., preserves
request immutability), `@precondition` (req.projectDir and req.pid must be
provided and valid), `@postcondition` (resolves to an object with output string —
original output or "Done." when empty), and `@complexity` (time O(n) and space
O(n) where n is the length of captured output); keep the description concise and
mention error mapping via toApiError so callers know errors are converted to API
errors.

packages/api/src/services/auth.ts (4)

114-148: ⚡ Quick win

Add comprehensive TSDoc for Claude auth functions.

The three Claude auth functions (runAuthClaudeLogin, runAuthClaudeStatus, runAuthClaudeLogout) lack individual TSDoc documentation.

📝 Suggested documentation pattern

For runAuthClaudeLogin:

// CHANGE: authenticate with Claude via REST API
// WHY: store Claude credentials through HTTP
// PRECONDITION: req.claudeAuthPath directory exists and is writable
// POSTCONDITION: Claude credentials stored with label
// COMPLEXITY: O(1) time, O(1) space
// PURITY: SHELL
// EFFECT: Effect<{ message: string }, ApiInternalError, FileSystem | Path | CommandExecutor>
// INVARIANT: captured log output forms the response body

Apply similar patterns to runAuthClaudeStatus and runAuthClaudeLogout.

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/auth.ts` around lines 114 - 148, Add comprehensive
TSDoc comments for each Claude auth wrapper: runAuthClaudeLogin,
runAuthClaudeStatus, and runAuthClaudeLogout; for each function include `@pure`
(true/false), `@effect` (list required services like FileSystem | Path |
CommandExecutor), `@invariant` (e.g., captured log output forms the response),
`@precondition` (e.g., req.claudeAuthPath directory exists and is writable),
`@postcondition` (what the function guarantees, e.g., credentials stored or status
returned), and `@complexity` (time/space Big-O). Place the TSDoc immediately above
each exported function (runAuthClaudeLogin, runAuthClaudeStatus,
runAuthClaudeLogout) following the suggested pattern in the review so tools and
reviewers can verify the annotations.

---

41-76: ⚡ Quick win

Add comprehensive TSDoc for GitHub auth functions.

The three GitHub auth functions (runAuthGithubLogin, runAuthGithubStatus, runAuthGithubLogout) lack individual TSDoc documentation.

📝 Suggested documentation pattern

For runAuthGithubLogin:

// CHANGE: authenticate with GitHub via REST API
// WHY: store GitHub token in env file through HTTP
// PRECONDITION: req.envGlobalPath exists and is writable
// POSTCONDITION: GitHub token stored with label in env file
// COMPLEXITY: O(n) time where n = env file size, O(1) space
// PURITY: SHELL
// EFFECT: Effect<{ message: string }, ApiInternalError, FileSystem | Path>
// INVARIANT: captured log output forms the response body

Apply similar patterns to runAuthGithubStatus and runAuthGithubLogout with appropriate postconditions.

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/auth.ts` around lines 41 - 76, Add comprehensive
TSDoc blocks above runAuthGithubLogin, runAuthGithubStatus, and
runAuthGithubLogout that follow the project pattern: include a short
description, `@pure` (true/false), `@effect` listing required services (e.g.,
FileSystem | Path | HTTP), `@invariant` describing the log-output-to-response
invariant, `@precondition` (e.g., envGlobalPath exists/writable), `@postcondition`
(what the function guarantees, e.g., token stored or status reported or label
removed), and `@complexity` (time and space). Use the suggested template for
runAuthGithubLogin (authenticate via REST, store token in env file) and create
analogous, accurate postconditions for runAuthGithubStatus and
runAuthGithubLogout; place these TSDoc comments immediately above each function
declaration (runAuthGithubLogin, runAuthGithubStatus, runAuthGithubLogout).

---

78-112: ⚡ Quick win

Add comprehensive TSDoc for Codex auth functions.

The three Codex auth functions (runAuthCodexLogin, runAuthCodexStatus, runAuthCodexLogout) lack individual TSDoc documentation.

📝 Suggested documentation pattern

For runAuthCodexLogin:

// CHANGE: authenticate with Codex via REST API
// WHY: store Codex credentials through HTTP
// PRECONDITION: req.codexAuthPath directory exists and is writable
// POSTCONDITION: Codex credentials stored with label
// COMPLEXITY: O(1) time, O(1) space
// PURITY: SHELL
// EFFECT: Effect<{ message: string }, ApiInternalError, FileSystem | Path | CommandExecutor>
// INVARIANT: captured log output forms the response body

Apply similar patterns to runAuthCodexStatus and runAuthCodexLogout.

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/auth.ts` around lines 78 - 112, The three exported
functions runAuthCodexLogin, runAuthCodexStatus, and runAuthCodexLogout are
missing the required comprehensive TSDoc; add a TSDoc block immediately above
each function that follows the project's pattern and includes: a short
description, `@pure` (true/false), `@effect` listing required services (e.g.,
FileSystem | Path | CommandExecutor), `@invariant` describing the
response/log-output invariant, `@precondition` (e.g., req.codexAuthPath exists and
writable), `@postcondition` (what the function guarantees, e.g., credentials
stored or status returned), and `@complexity` (time and space); ensure the text
references the function behavior (e.g., "authenticate with Codex via REST API"
for runAuthCodexLogin, "query stored Codex credentials" for runAuthCodexStatus,
"remove stored Codex credentials" for runAuthCodexLogout) so reviewers can match
intent to implementation.

---

34-40: ⚡ Quick win

Complete TSDoc documentation with missing mandatory fields.

The functional comments provide useful context, but @precondition and @postcondition markers are missing.

📝 Add missing TSDoc fields

 // CHANGE: expose lib auth functions through REST API
 // WHY: CLI becomes HTTP client; all auth operations run on API server
+// PRECONDITION: env file paths exist and are writable
+// POSTCONDITION: auth tokens stored/retrieved/removed from env files
 // PURITY: SHELL
 // EFFECT: Effect<AuthStatusResponse, ApiInternalError, FileSystem | Path | CommandExecutor>
 // INVARIANT: captured log messages form the response body
 // COMPLEXITY: O(n) where n = env file size

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/auth.ts` around lines 34 - 40, The TSDoc block for
the auth REST wrapper (the comment starting "// CHANGE: expose lib auth
functions through REST API") is missing required `@precondition` and
`@postcondition` tags; update the TSDoc for the function that exposes lib auth
functions through REST API (the auth service entrypoint in
packages/api/src/services/auth.ts) to include a `@precondition` that specifies
required runtime conditions (e.g., env vars present, file system/Path
accessible, network available, and CommandExecutor/cli libs initialized) and a
`@postcondition` that specifies observable outcomes (returns AuthStatusResponse or
throws/returns ApiInternalError, persists captured log messages in the response
body, and may modify FileSystem/Path/CommandExecutor state); ensure the existing
`@pure/`@effect/@invariant/@complexity tags remain intact and that wording is
concise and machine-readable.

packages/lib/src/usecases/actions/create-project.ts (1)

99-107: ⚡ Quick win

Add comprehensive TSDoc for resolveSshHost.

This CORE layer function has functional comments but lacks comprehensive TSDoc. Per coding guidelines, all functions require @pure, @effect, @invariant, @precondition, @postcondition, and @complexity markers.

📝 Complete TSDoc documentation

 // CHANGE: detect DinD for SSH host resolution
 // WHY: in DinD, localhost:mappedPort is on outer host; use containerName:22 via Docker DNS
+// QUOTE(ТЗ): n/a
+// REF: n/a
+// SOURCE: n/a
+// FORMAT THEOREM: ∀ config: isInsideDocker() → (containerName, 22) ∧ ¬isInsideDocker() → (localhost, sshPort)
 // PURITY: CORE
+// EFFECT: none (pure function)
+// INVARIANT: returns host/port pair for SSH connection
+// PRECONDITION: config.containerName and config.sshPort are valid
+// POSTCONDITION: returns Docker DNS host in DinD, localhost otherwise
+// COMPLEXITY: O(1) time, O(1) space
+/**
+ * Resolve SSH connection host and port based on runtime environment.
+ * `@param` config - project template configuration
+ * `@returns` SSH target with host and port
+ * `@pure` true
+ * `@effect` none
+ * `@invariant` DinD → containerName:22, otherwise localhost:sshPort
+ * `@precondition` config has valid containerName and sshPort
+ * `@postcondition` returns appropriate SSH target for environment
+ * `@complexity` O(1) time, O(1) space
+ */
 
 const resolveSshHost = (config: CreateCommand["config"]): { host: string; port: number } =>

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space), @throws Never (errors must be typed in Effect)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/lib/src/usecases/actions/create-project.ts` around lines 99 - 107,
Add comprehensive TSDoc to the resolveSshHost function: document it with `@pure`
(true), `@effect` (none or list any required services), `@invariant` (describe
host/port mapping invariants such as port ∈ ℕ and host non-empty), `@precondition`
(expects valid CreateCommand["config"] with containerName and sshPort),
`@postcondition` (returns an object with host:string and port:number; when
isInsideDocker() true host==config.containerName && port==22 else
host=="localhost" && port==config.sshPort), `@complexity` (time O(1), space O(1)),
and `@throws` Never; reference the function name resolveSshHost and the config
shape CreateCommand["config"] in the TSDoc so reviewers can locate the behavior
and guarantees.

packages/api/src/services/projects.ts (2)

344-353: ⚡ Quick win

Add comprehensive TSDoc for downAllProjects.

This exported function lacks all required documentation. Per coding guidelines, functions must include TSDoc with @pure, @effect, @invariant, @precondition, @postcondition, and @complexity.

📝 Suggested documentation

+// CHANGE: stop all docker-git project containers
+// WHY: provide batch shutdown operation via REST API
+// QUOTE(ТЗ): n/a
+// REF: n/a
+// SOURCE: n/a
+// FORMAT THEOREM: ∀ projects: downAll() → ∀p ∈ projects: status(p) = stopped
+// PURITY: SHELL
+// EFFECT: Effect<void, ApiInternalError, CommandExecutor | FileSystem | Path>
+// INVARIANT: all project containers stopped on success
+// PRECONDITION: Docker daemon accessible
+// POSTCONDITION: all docker-git containers stopped
+// COMPLEXITY: O(n) time where n = number of projects, O(1) space
 export const downAllProjects = () =>

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/projects.ts` around lines 344 - 353, Add
comprehensive TSDoc to the exported function downAllProjects: document whether
it is pure with `@pure`, list required services/effects (e.g., uses
downAllDockerGitProjects/Effect) with `@effect`, state any invariants for the
operation with `@invariant`, declare input preconditions (if any) with
`@precondition`, describe expected postconditions (e.g., that all projects are
shut down or an ApiInternalError is returned) with `@postcondition`, and include
computational complexity (time/space) with `@complexity`; place the TSDoc
immediately above the downAllProjects declaration and reference
downAllDockerGitProjects in the `@effect` text so readers can locate the
dependency.

---

355-380: ⚡ Quick win

Add comprehensive TSDoc for applyProject.

This exported function is missing all required documentation markers. Per coding guidelines, all functions must include comprehensive TSDoc.

📝 Suggested documentation

+// CHANGE: apply configuration changes to existing project
+// WHY: allow runtime updates to token labels, resource limits, and MCP Playwright
+// QUOTE(ТЗ): n/a
+// REF: n/a
+// SOURCE: n/a
+// FORMAT THEOREM: ∀ project: apply(project, config) → project' with config applied
+// PURITY: SHELL
+// EFFECT: Effect<{ applied: boolean, containerName: string }, ApiInternalError | ApiNotFoundError, CommandExecutor | FileSystem | Path>
+// INVARIANT: project configuration updated on success
+// PRECONDITION: projectId exists in project index
+// POSTCONDITION: project template reflects request config changes
+// COMPLEXITY: O(m) time where m = size of project config, O(1) space
 export const applyProject = (projectId: string, request: ApplyRequest) =>

As per coding guidelines, "Document all functions with comprehensive TSDoc including: @pure (true/false), @effect (required services), @invariant (mathematical invariants), @precondition, @postcondition, @complexity (time and space)."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/api/src/services/projects.ts` around lines 355 - 380, The exported
function applyProject is missing the required comprehensive TSDoc; add a TSDoc
block immediately above the applyProject declaration that documents its purpose,
parameters (projectId, request/ApplyRequest), and return type (Effect/Observable
pipeline result), and include the required tags: `@pure` (true/false), `@effect`
(list required services/dependencies used like getProject, applyProjectConfig),
`@invariant` (any invariants on inputs/outputs), `@precondition` (e.g., non-empty
projectId, valid request fields), `@postcondition` (applied===true when successful
and containerName set), and `@complexity` (time and space complexity), keeping
descriptions concise and accurate to the implementation.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes